home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 47.7z / BS1 part 47 / UGA Utilities 6 (1989)(United Graphic Artists)(PD).7z / UGA Utilities 6 (1989)(United Graphic Artists)(PD).adf / a.doc < prev    next >
Text File  |  1988-01-19  |  22KB  |  493 lines
  1.  
  2.  
  3.  
  4.                        Power Packer V2.1b User Manual
  5.  
  6.                                March 21, 1989
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13.      Congratulations, you have just obtained a copy of Power Peak's new and
  14. improved PowerPacker 2.1b.  If you have suggestions or remarks about this
  15. program, or if you find any bugs, please let me know.
  16.      This version of the PowerPacker is shareware, this means that if you use
  17. it a lot I would appreciate it if you'd send me a contribution of $10 or the
  18. same amount in any other currency.  This money will enable me to produce more
  19. programs on the Amiga.  If you send $15 I will send you the latest version of
  20. the PowerPacker.
  21.      Write to the following address:
  22.  
  23.                                 François Nico
  24.                                 Corbielaan 13
  25.                              3060 Bertem BELGIUM
  26.  
  27.  
  28. Contents
  29. ========
  30.  
  31. 1. The Packer
  32.      1.1 An introduction
  33.      1.2 The file requester
  34.      1.3 The basic menus
  35.           1.3.1 Project
  36.           1.3.2 Prefs
  37.  
  38. 2. Recrunch
  39.      2.1 How ?
  40.      2.2 Why ?
  41.  
  42. 3. The HunkLab
  43.      3.1 Preferences
  44.      3.2 Process file
  45.  
  46. 4. The Script Menu
  47.  
  48. 5. The Supervisor Window
  49.  
  50. 6. A Sample Session
  51.  
  52. 7. PowerPacker 2.1b & the CLI
  53.  
  54.  
  55. 1. The Packer
  56. -------------
  57.  
  58. 1.1 An introduction
  59.  
  60.      The PowerPacker is a userfriendly command and data cruncher, this means
  61. a menu driven utility that can crunch almost any file on your disks.  When
  62. you use it for the first time it's best to maintain a certain order in your
  63. actions (as we will see in chapter 6 of this document):
  64.  
  65.   (a) set the packer options at the beginning of a session (Prefs menu)
  66.   (b) load the file from disk (Project menu)
  67.   (c) save the file back to disk (Project menu)
  68.  
  69.      Apart from the crunching, you can also recrunch files that were crunched
  70. by some other crunchers.
  71.      The HunkLab enables you to e.g. force code or data in chip ram.
  72.      The script, a new feature in 2.1b, allows you to e.g. crunch a dozen of
  73. files overnight.
  74.  
  75.      Before I demonstrate how to use the PowerPacker, let's look at the file
  76. requester and a brief overview of the menus and capabilities.
  77.  
  78.  
  79. 1.2 The file requester
  80.  
  81.     Whenever you are required to enter a filename, the packer sets up a file
  82. requester.  This requester automatically contains all devices connected to
  83. your Amiga and lists all the files (and their length) of a selected
  84. directory.  You don't have to wait for the directory read to end.  You can
  85. select a file or directory the moment you see it, or you can enter it in the
  86. appropriate string gadget.
  87.  
  88.     However, if you wait for the directory read to end and quit the file
  89. requester, the next time you use it all the files will still be there, so you
  90. don't have to wait for the directory to be read again (This is very useful
  91. when you are recording a script, as you'll see later).  This feature has one
  92. disadvantage :  if files are changed or added to the selected directory they
  93. won't be shown in the list, or they will be shown with the wrong filelength,
  94. the next time the requester appears.  Therefore, if you think anything has
  95. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  96. the directory.  (E.g.  when you save a crunched file on top of the old one,
  97. the old file length will be shown in the requester.)
  98.  
  99.  
  100. 1.3 The basic menus
  101.  
  102. 1.3.1 Project
  103.  
  104.     The project menu contains the file manipulation options.  Most of them
  105. speak for themselves:
  106.  
  107.   Load      ->  Load a file from disk and start the (de)crunching.
  108.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  109.   Delete    ->  Delete a file from disk.
  110.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  111.   About...  ->  Show general information and my address.
  112.   Quit      ->  Quit the program.
  113.  
  114. 1.3.2 Prefs
  115.  
  116.      The prefs menu contains all the (de)cruncher settings.  You can select
  117. to (de)crunch command files or a data files.  If you want the crunched
  118. version of your file to be executable, select 'Command file'.  Now the
  119. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  120. you want to crunch only contains data (e.g. Source codes of your own
  121. programs), select the 'Data file' option.  This can be handy if you're going
  122. to use the PowerPacker CLI commands.  I'll discuss these commands in chapter
  123. 5 of this document.  Finally you have to choose whether you want to crunch or
  124. decrunch the load file.
  125.  
  126. Note: - The PowerPacker will automatically decrunch a previously crunched
  127.         file.  You don't have to select crunch or decrunch mode anymore as
  128.         in PowerPacker 2.0a.
  129.  
  130.      The 'Decrunch Color' submenu contains the following options :
  131.  
  132.   Color 0   ->  The background color will change while decrunching
  133.   Color 1   ->  The text color changes
  134.   Pointer   ->  Only the mousepointer's color changes
  135.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  136.   None      ->  If you're eyes are wearing out.
  137.  
  138.      These options indicate what color will flash when a file is decrunched.
  139. You can change this option before saving a crunched file, so you can save a
  140. version of your crunched program that flashes in color 1, and one that
  141. flashes in the mouse pointer.
  142.      If the 'Color Crunch' option is selected, the PowerPacker will use the
  143. same color while crunching the file, giving you an idea what the decrunching
  144. will look like (provided that you don't change any options just before saving
  145. to disk).  The default value is color 1.
  146.  
  147.      In the efficiency submenu you will find the following possibilities :
  148.  
  149.   Fast      ->  Use for small files, or for quick crunch.
  150.   Mediocre  ->  Better but slower.
  151.   Good      ->  Default, gains 40-50% in most cases.
  152.   Very Good ->  Also very slow !
  153.   Best      ->  Advised for script use only, ultra slow !!!
  154.  
  155. Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  156.         2 times slower and 'Best' 4 times.
  157.  
  158.      You can set Amiga's multitasking off to increase the crunching speed
  159. (slightly).  The default setting is on.  When you want to use the PowerPacker
  160. in a multitasking environment, you'll probably start a crunching job and at
  161. the same time continue your work.  In that case, it might be interesting to
  162. set the 'LED Crunch' option on.  Now your power-LED flashes while crunching,
  163. just like the screencolors.  (but I presume they're already turned off
  164. because editing a file with flashing text really gets on your nerves)
  165.      You can even turn off your monitor and still see when the cruncher has
  166. finished.
  167.  
  168.      Finally, you can set the paging in the supervisor window on so you can
  169. read the crunch and hunk information, without everything racing off the
  170. screen before you've had a chance to see it.
  171.  
  172. Note: - While crunching, you can press both mousebuttons at the same
  173.         time to abort.
  174.       - Do *NOT* change disks when you are crunching with the multitasking
  175.         switched off !!!  The Amiga will crash !!!
  176.  
  177. 2. Recrunch
  178. -----------
  179.  
  180. 2.1 How ?
  181.  
  182.      This menu is provided for the people who were using another cruncher or
  183. an older version of the PowerPacker.  Just select 'Recrunch File' or
  184. 'Decrunch Only' and load the file.  The PowerPacker will start the correct
  185. decrunch algorithm.  If you selected 'Recrunch' the PowerPacker will start to
  186. crunch the decrunched file.  If the PowerPacker doesn't recognize the
  187. cruncher it will say so, no harm is done.  If you select 'Recrunch Always'
  188. the PowerPacker will always recrunch, even if the file was crunched with this
  189. version of the PowerPacker.  Useful for recrunching files using a higher
  190. efficiency.  (E.g. recrunch a 'Fast' crunched file in 'Best')
  191.  
  192.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  193. 'Relokit 1.0' and older PowerPacker files.  If you'd like to see other
  194. crunchers supported, send me the cruncher and some programs crunched with it.
  195. (With a contribution I hope).  If it is possible to develop a decrunch
  196. algorithm I will include it in the next version of the PowerPacker.
  197.  
  198. 2.2 Why ?
  199.  
  200.      The PowerPacker always crunches better than the 'ANC Cruncher' and the
  201. 'TNM Cruncher'.  It crunches better than 'Relokit' most of the time, but even
  202. if it doesn't, I advise you to recrunch because 'Relokit' has some serious
  203. disadvantages (e.g. while the decrunched file is running, the crunched
  204. version still eats memory).  In contrast the PowerPacker only eats about 580
  205. bytes while your file is running, and (of course) frees it afterwards.
  206.  
  207. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the
  208.         PowerPacker just replaces the file header with the improved and
  209.         debugged 2.1 header. (Unless you've selected 'Recrunch Always')
  210.       - The recrunch menu only supports command files !  You can't recrunch
  211.         data files from e.g. PowerPacker 1.0, sorry.
  212.  
  213. 2. The Hunklab
  214. --------------
  215.  
  216. 2.1 Preferences
  217.  
  218.      This menu is not really part of the PowerPacker crunch/decrunch routines
  219. but it wasn't worth writing a separate program for and a HunkLab is after all
  220. a very interesting utility.  You can e.g. use it to remove symbol and debug
  221. hunks from files that wouldn't crunch otherwise.
  222.  
  223.      You can force a program's code, data or BSS (uninitialised data) into
  224. chip ram or you can remove symbol tables and debug information just by
  225. toggling the marker on/off.  So in future, when you want your programs to be
  226. able to run on a one megabyte system, a simple click on the mousebutton will
  227. do.
  228.  
  229. 2.2 Process file
  230.  
  231.      'Process file' reads the file from disk and changes it according to your
  232. preferences.  To save the processed file, use 'Save' from the Project menu.
  233.      'Process & Crunch' will process the file and crunch the file afterwards
  234. (if possible).  To save use 'Save' in the Project menu.
  235.  
  236.  
  237. 3. The Script Menu
  238. ------------------
  239.  
  240.      This menu is a new feature in version 2.1b.  It allows you to record 80
  241. different commands to be executed after each other.  It is ideal for
  242. crunching a lot of files overnight.  Menu options are:
  243.  
  244.      'Clear Script' and 'List Script' will do just that.
  245.      'Script Log File' is used to specify a file to redirect output to.  If
  246.           you cancel the requester no log file is used.
  247.      'Destination Dir' is used to specify the directory to save to.  It is
  248.           ghosted in the normal use.
  249.      'Start Recording' is used to start the recording of the script. If the
  250.           script was empty you will be asked for the destination directory.
  251.           You will also be asked whether to append '.pp21' to the destination
  252.           file.  You're advised to do this for data files.
  253.               After selecting the destination you can start entering the
  254.           script commands.  Everything that is ghosted is not available as a
  255.           command.  Just enter everything as if you were actually using the
  256.           PowerPacker.  When you e.g. choose 'Load' the PowerPacker will
  257.           ask a list of files to be (de)crunched. Press 'CANCEL' to exit the
  258.           entry.
  259.           Note: - You can still change the source and destination dir while
  260.                   recording.
  261.           Every command you enter will be displayed in the supervisor window.
  262.      'Stop Recording' is used to exit the recording mode.
  263.      'Delete Last' will delete the last command after a confirmation.
  264.      'Execute Script' finally, is used to start the playback of the script
  265.           commands.  If you press the menu button a requester will appear to
  266.           ask you if you want to abort the script execution.
  267.               After executing the script a request to clear the script will
  268.           appear.
  269.  
  270. Note: - It is advisable to let the filerequester buffer fill before you
  271.         start selecting files.  It is also better not to change the source
  272.         directory too often.
  273.         - The screen turns grey to indicate a script is executing.
  274.       - While executing a script, the PowerPacker will always act
  275.         destructive !  Files will allways be overwritten and deleted !!!
  276.  
  277. 4. The Supervisor Window
  278. ------------------------
  279.  
  280.      This window displays all kind of useful information like the file
  281. status, crunch messages, and error messages.  You can follow all steps, from
  282. the original file that is loaded into memory, to the final crunched version
  283. on disk.  When an executable file is loaded, its hunk information is
  284. displayed.  This information is rather technical, but it can be useful for
  285. programmers.  If you're not interested, just ignore it.
  286.  
  287.      I think it might be useful to give a list of possible error messages:
  288.  
  289. (De)crunch :  Buffer overflow !
  290.                 (Crunched file is getting longer than original file)
  291.               Crunch aborted !
  292.                 (Crunching stopped by user or by buffer overflow)
  293.               No memory for decrunch buffer !
  294.               Out of memory !
  295.                 (Buy some more, or try closing the WorkBench)
  296.               Sorry, can't crunch !
  297.                 (This is a polite program)
  298.               Can't find hunk_header.
  299.               Hunk not allowed in load file!
  300.               Unknown Hunk !
  301.                 (Not a command file)
  302.               Hunk not supported (yet ?) !
  303.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  304.               Nothing to save !
  305.                 (Buffer is empty)
  306.               Save Aborted !
  307.               Error reading file !
  308.               Can't open file !
  309.               Error writing data header !
  310.               Error writing buffer !
  311.               File not found !
  312.               Couldn't delete file !
  313.               Can't open file !
  314.                 (Disk errors)
  315.  
  316. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  317.               Replacing 1.1 decrunch header with 2.1 header...
  318.                 (2.1 header is shorter and bugfree, 1.1 isn't !!)
  319.               No need to recrunch 'PowerPacker 2.0' command file,
  320.               Replacing 2.0 decrunch header with 2.1 header...
  321.                 (There was still a small bug in 2.0 header, so replace it.)
  322.               Not crunched with one of the supported crunchers !!
  323.                 (Or file is not crunched at all !)
  324.               Sorry, can't recrunch !
  325.                 (We're always polite)
  326.  
  327. Process :     Sorry, can't process file !
  328.                 (File is probably not a command file)
  329.               Can't crunch file !
  330.                 (File still contains unsupported hunks)
  331.  
  332. Script :      Script buffer full !! Please stop recording.
  333.                 (Script is limited to 80 commands, choose 'Stop Recording')
  334.  
  335. 5. A Sample Session
  336. -------------------
  337.  
  338.      Now that I have explained the PowerPacker's capabilities, it's time for
  339. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  340. System directory on your Workbench 1.2 disk.
  341.  
  342.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  343. text, it was very late and I couldn't stand the other decrunch colors
  344. anymore !)
  345.  
  346.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  347. (a file requester will appear), insert your WorkBench 1.2 disk and choose the
  348. 'CLI' command in the system directory.  Now you'll see a lot of hunk
  349. information about the CLI command:
  350.  
  351.                                                                              
  352.      Loading command file 'df0:System/CLI'...                                
  353.                                                                              
  354.      Hunk_header (0x03F3)                                                    
  355.         9 hunks (0 to 8).                                                    
  356.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  357.                Hunk_reloc32 (0x03EC)                                         
  358.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  359.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  360.                Hunk_reloc32 (0x03EC)                                         
  361.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  362.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  363.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  364.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  365.                Hunk_reloc32 (0x03EC)                                         
  366.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  367.                Hunk_reloc32 (0x03EC)                                         
  368.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  369.                                                                              
  370.      Crunching command file...                                                  
  371.      Press left and right button to abort.                                   
  372.      Crunching, please wait.                                                 
  374.  
  375.      The cruncher displays the percentage of the file already crunched and
  376. after some time your screen will look like this:
  377.  
  378.                                                                              
  379.      100% crunched.                                                          
  380.      Done.                                                                   
  381.      Original length : 2356 bytes.                                           
  382.      Crunched length : 1204 (1776) bytes.                                    
  383.      Gained 49% (1152 bytes) !                                               
  385.  
  386.      The only thing you have to do now is save this back to disk as an
  387. executable file.  Now enjoy the crunched CLI command.
  388.  
  389.  
  390. 6. PowerPacker 2.1b & the CLI
  391. -----------------------------
  392.  
  393.      For your convenience, I have also written two CLI commands, one to
  394. crunch and one to decrunch.
  395.      Attention:  These commands only (de)crunch DATA files !!!!  (So to
  396. crunch executable files, you'll still have to use the PowerPacker 2.1b).
  397.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  398. arguments.  You'll get something like this:
  399.  
  400. 1>
  401. 1> crunch
  402. POWER-PACKER 2.1a Data Cruncher.
  403.   Written by Lone Wolf from POWERPEAK.
  404. USAGE : Crunch <source> <destination> [efficiency (1-5) default 3] [P] [F]
  405.         Where P stands for no percentage, F for Forbid() crunching.
  406. 1>
  407. 1> decrunch
  408. POWER-PACKER 2.1a Data Decruncher.
  409.   Written by Lone Wolf from POWERPEAK.
  410. USAGE : Decrunch <source> <destination> [decrunch color (0-4)]
  411.    With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None
  412.    If <destination> is a * the file will be typed to Output().
  413. 1>
  414.  
  415.      These commands are useful to be included in your startup-sequence or to
  416. read crunched text files quickly.
  417.  
  418.      I don't think these commands need any further explanation.  Just try
  419. them out and you'll see what happens.  E.g. when you have a crunched source
  420. file of a program on your disk, typing
  421.  
  422.      Decrunch filename.c *
  423.  
  424. will display the file as if you were using the 'Type' command for textfiles.
  425.  
  426.                                                    Enjoy !!!
  427.  
  428.  
  429.                               PROGRAM HISTORY:
  430.  
  431. *****************************************************************************
  432. VERSION 1.0a
  433.  
  434.      First release.
  435.  
  436. *****************************************************************************
  437. VERSION 1.1a
  438.  
  439.      Fixed bugs.
  440.      Improved crunch algorithm by about 5%.
  441.      'Delete' and 'Multitask' added.
  442.      Better menu structure.
  443.      Improved the file requester.
  444.      Written CLI commands.
  445.  
  446. *****************************************************************************
  447. VERSION 2.0a
  448.  
  449.      Fixed some more bugs.
  450.      Added buffer and automatic device-list to the file requester.
  451.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  452.      and 'Paging'.
  453.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  454.      Added the hunklab.
  455.      Improved CLI commands.
  456.  
  457. *****************************************************************************
  458. VERSION 2.1a
  459.  
  460.      Fixed last bug in header (2.0 crashed when you were out of mem)
  461.      Added script feature, now possible to crunch files overnight.
  462.      Improved requesters.
  463.      Automatic crunch/decrunch.
  464.      Improved menu structure considerably.
  465.      Intelligent recrunch implemented.
  466.      Automatic crunch/decrunch.
  467.      Added 'Color Crunch' option.
  468.      New efficiency 'Best' added.
  469.  
  470. *****************************************************************************
  471. VERSION 2.1b
  472.  
  473.      Bug fixed in script abort.
  474.      Added ability to open a log file during script execute.
  475.      Now possible to recrunch PowerPacker files with a higher efficiency.
  476.      Recrunch detects unsupported crunchers a lot faster.
  477.      Version supposed to work on NTSC Amiga (not tested !)
  478.  
  479. *****************************************************************************
  480.  
  481.  
  482. P.S. This text file crunched to 42% of it's original length. (Gained 58% !)
  483.  
  484. The PowerPacker 2.1b written by François Nico (Lone Wolf).
  485. Special thanks to Pauwels Luc (Red Eagle) for writing the 2.0a manual and
  486.                   Tybergein Jorrit (Edain) for the extensive debugging.
  487.  
  488. (c) 1989 François Nico / Power Peak
  489.  
  490.                                    //
  491.                        Thanks to \X/ Amiga for being the best computer ever !
  492.  
  493.